Wheeli jaotusformaat: binaarsete pakettide loomine Pythoni jaoks

Pythoni ökosüsteem tugineb suuresti tõhusale pakettihaldusele. Üks selle ökosüsteemi nurgakive on Wheeli jaotusformaat, mida sageli tähistatakse .whl laiendiga. See juhend süveneb Wheeli formaadi keerukusse, selle eelistesse ja sellesse, kuidas luua Pythoni jaoks binaarpakette, rahuldades arendajaid kogu maailmas, kes soovivad sujuvat ja usaldusväärset tarkvara levitamist.

Mis on Wheeli formaat?

Wheeli formaat on Pythoni jaoks ehitatud pakettformaat. See on loodud nii, et seda oleks lihtsam paigaldada kui lähtekoodijaotusi (sdist). See asendab vanema egg-formaadi, lahendades mitmed selle puudused. Põhimõtteliselt on see ZIP-arhiiv spetsiifilise struktuuri ja metaandmetega, mis võimaldab pip-il ja teistel paigaldustööriistadel paketi kiiresti paigaldada ilma seda lähtekoodist ehitamata.

Wheeli peamised omadused

• Platvormist sõltumatus (kus kohaldatav): Wheele saab ehitada konkreetsete platvormide ja arhitektuuride jaoks (nt Windows 64-bitine, Linux x86_64) või olla platvormist sõltumatud (puhas Python). See võimaldab luua optimeeritud binaare erinevate operatsioonisüsteemide jaoks.
• Lihtne paigaldamine: Wheeli formaat sisaldab eelnevalt ehitatud jaotusi, mis minimeerib paigaldamise ajal koodi kompileerimise vajadust. See kiirendab oluliselt paigaldusprotsessi, eriti C-laiendite või muude kompileeritud komponentidega pakettide puhul.
• Metaandmete kaasamine: Wheelid sisaldavad kogu paketi kohta vajalikke metaandmeid, sealhulgas sõltuvusi, versiooniinfot ja sisenemispunkte. Need metaandmed on kriitilise tähtsusega pakettihalduritele nagu pip sõltuvuste haldamiseks ja paketi õigeks paigaldamiseks.
• Aatomiline paigaldamine: pip paigaldab paketid Wheelidest aatomiliselt. See tähendab, et paigaldus kas lõpeb edukalt või tühistatakse täielikult, vältides osaliselt paigaldatud pakette, mis võivad viia ebakõladeni.
• Korratavus: Wheelid parandavad korratavust, pakkudes järjepidevat ehitatud artefakti, mida saab paigaldada mitmesse keskkonda ilma ümberkompileerimist vajamata (eeldusel, et sihtplatvorm ühtib).

Miks kasutada Wheele?

Wheeli valimine lähtekoodijaotuste asemel pakub mitmeid eeliseid, lihtsustades paketi paigaldamise ja juurutamise protsessi. Siin on peamiste eeliste jaotus:

Kiiremad paigaldusajad

Üks Wheeli olulisemaid eeliseid on nende kiirus. Pakkudes eelnevalt ehitatud jaotusi, välistavad Wheelid paigaldamise ajal koodi kompileerimise vajaduse. See on eriti kasulik C-s, C++-is või muudes keeltes kirjutatud kompileeritud laiendustega pakettide puhul. Kujutage ette keeruka teadusraamatukogu juurutamist; Wheeli kasutamine vähendab oluliselt seadistamisaega lõppkasutaja masinatel.

Näide: numpy lähtekoodist paigaldamine võib võtta mitu minutit, eriti vanemal riistvaral. Wheeli paigaldamine võtab tavaliselt sekundeid.

Vähendatud sõltuvus ehitustööriistadest

Pakettide lähtekoodist paigaldamine nõuab sageli, et kasutajatel oleks süsteemi paigaldatud vajalikud ehitustööriistad (kompilaatorid, päised jne). See võib olla sisenemisbarjäär, eriti kasutajatele, kes pole tarkvaraarendusega tuttavad. Wheelid eemaldavad selle sõltuvuse, muutes paigaldamise lihtsamaks ja ligipääsetavamaks.

Näide: Andmeteadlasel uurimislaboris ei pruugi olla vajalikke kompilaatoreid paketi lähtekoodist ehitamiseks. Wheel võimaldab neil paketi otse paigaldada ilma keskkonda konfigureerimata.

Parem usaldusväärsus

Pakkudes eelnevalt ehitatud binaare, tagavad Wheelid, et pakett paigaldatakse järjepidevalt erinevatesse keskkondadesse. See vähendab paigaldusvigade riski, mis on tingitud süsteemi konfiguratsioonide või ehitustööriistade versioonide erinevustest. See järjepidevus on ülitähtis rakenduste jaoks, mis nõuavad stabiilset ja prognoositavat käitumist.

Näide: Mitmele serverile juurutatud veebirakendus peab omama järjepidevaid pakettversioone. Wheeli kasutamine tagab, et igale serverile paigaldatakse samad binaarid, minimeerides juurutamisprobleemide riski.

Täiustatud turvalisus

Wheele saab allkirjastada, et kontrollida nende autentsust ja terviklikkust. See aitab vältida pahatahtlike osapoolte rikutud pakettide levitamist. Pakettide allkirjastamine pakub täiendavat turvalisuse kihti, tagades, et kasutajad paigaldavad usaldusväärset tarkvara.

Näide: Organisatsioonid saavad rakendada poliitikaid, mis nõuavad kõigi pakettide allkirjastamist enne tootmiskeskkonda juurutamist. See kaitseb tarneahelate rünnakute eest, kus pakettidesse süstitakse pahatahtlikku koodi.

Wheeli pakettide loomine: samm-sammult juhend

Wheeli pakettide loomine on lihtne protsess, mis hõlmab setuptools-i ja wheel-pakettide kasutamist. Siin on üksikasjalik juhend:

1. Projekti seadistamine

Kõigepealt veenduge, et teie projekt on korralikult struktureeritud. Minimaalselt vajate setup.py faili ja paketi lähtekoodi.

Projekti struktuuri näide:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. Fail setup.py

Fail setup.py on teie projekti süda. See sisaldab teavet teie paketi metaandmete kohta ja määrab, kuidas seda ehitada ja paigaldada. Siin on näide setup.py failist:

from setuptools import setup, find_packages

setup(
 name='my_package',
 version='0.1.0',
 description='A simple example package',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/your_username/my_package',
 author='Your Name',
 author_email='your.email@example.com',
 license='MIT',
 packages=find_packages(),
 install_requires=['requests'],
 classifiers=[
 'Development Status :: 3 - Alpha',
 'Intended Audience :: Developers',
 'License :: OSI Approved :: MIT License',
 'Programming Language :: Python :: 3',
 'Programming Language :: Python :: 3.6',
 'Programming Language :: Python :: 3.7',
 'Programming Language :: Python :: 3.8',
 'Programming Language :: Python :: 3.9',
 ],
)

Peamiste väljade selgitus:

• name: Teie paketi nimi. See on nimi, mida kasutajad kasutavad teie paketi paigaldamiseks (nt pip install my_package).
• version: Teie paketi versiooninumber. Järgige semantilist versioonimist (SemVer) järjepidevaks versioonimiseks (nt 0.1.0, 1.0.0, 2.5.1).
• description: Teie paketi lühikirjeldus.
• long_description: Teie paketi üksikasjalik kirjeldus. See loetakse sageli README.md failist.
• url: Teie paketi kodulehe või hoidla URL.
• author: Paketi autori nimi.
• author_email: Paketi autori e-posti aadress.
• license: Litsents, mille alusel teie pakett on levitatud (nt MIT, Apache 2.0, GPL).
• packages: Pakettide loend, mis kaasatakse teie jaotusse. find_packages() leiab automaatselt kõik paketid teie projektis.
• install_requires: Sõltuvuste loend, mida teie pakett vajab. pip paigaldab need sõltuvused automaatselt, kui teie pakett paigaldatakse.
• classifiers: Metaandmed, mis aitavad kasutajatel teie paketti PyPI-st (Python Package Index) leida. Need klassifikaatorid kirjeldavad arendusolekut, sihtrühma, litsentsi ja toetatud Pythoni versioone.

3. wheel-i paigaldamine

Kui teil pole wheel-paketti paigaldatud, saate selle paigaldada, kasutades pip-i:

pip install wheel

4. Wheeli paketi ehitamine

Liikuge oma projekti juurkataloogi (kus asub setup.py) ja käivitage järgmine käsk:

python setup.py bdist_wheel

See käsk loob dist kataloogi, mis sisaldab Wheeli paketti (.whl fail) ja lähtekoodi jaotust (.tar.gz fail).

5. Wheeli faili leidmine

Genereeritud Wheeli fail asub dist kataloogis. Selle nimi järgib formaati package_name-version-pyXX-none-any.whl, kus:

• package_name: Teie paketi nimi.
• version: Teie paketi versiooninumber.
• pyXX: Pythoni versioon, millega pakett ühildub (nt py37 Python 3.7 jaoks).
• none: Näitab, et pakett ei ole platvormispetsiifiline.
• any: Näitab, et pakett ühildub mis tahes arhitektuuriga.

Platvormispetsiifiliste wheelide puhul asendatakse none ja any sildid platvormi ja arhitektuuri identifikaatoritega (nt win_amd64 Windows 64-bitise jaoks).

6. Wheeli paketi testimine

Enne Wheeli paketi levitamist on oluline seda testida, et veenduda selle õiges paigalduses. Saate seda teha, kasutades pip-i:

pip install dist/my_package-0.1.0-py39-none-any.whl

Asendage dist/my_package-0.1.0-py39-none-any.whl oma Wheeli faili tegeliku teekonnaga.

7. Wheeli paketi levitamine

Pärast Wheeli paketi ehitamist ja testimist saate seda levitada erinevate kanalite kaudu:

• PyPI (Python Package Index): Kõige levinum viis Pythoni pakettide levitamiseks. Saate oma Wheeli paketi PyPI-sse üles laadida, kasutades twine-i.
• Privaatne paketiindeks: Organisatsioonisiseseks kasutamiseks saate seadistada privaatse paketiindeksi, kasutades tööriistu nagu devpi või Artifactory.
• Otsene levitamine: Saate oma Wheeli paketi otse kasutajatele levitada e-posti, failijagamise või muude vahendite kaudu.

C-laiendite ja platvormispetsiifiliste Wheelide käsitlemine

Platvormispetsiifiliste Wheelide, eriti C-laienditega Wheelide loomine nõuab lisasamme. Siin on protsessi ülevaade:

1. C-laiendite kompileerimine

C-laiendid tuleb kompileerida iga sihtplatvormi jaoks. See hõlmab tavaliselt C-kompilaatori (nt GCC, MSVC) ja platvormispetsiifiliste ehitustööriistade kasutamist.

Näide: Windowsis peate C-laiendite ehitamiseks kasutama Microsoft Visual C++ kompilaatorit. Linuxis kasutate tavaliselt GCC-d.

2. cffi või Cython-i kasutamine

Tööriistad nagu cffi ja Cython saavad C-laiendite loomise protsessi lihtsustada. cffi võimaldab teil kutsuda C-koodi otse Pythonist ilma C-koodi ise kirjutamata, samas kui Cython võimaldab teil kirjutada C-sarnast koodi, mis kompileeritakse C-laienditeks.

3. Platvormispetsiifiliste sõltuvuste määratlemine

Oma setup.py failis saate määratleda platvormispetsiifilisi sõltuvusi, kasutades parameetreid setup_requires ja install_requires. See võimaldab teil määrata erinevatele platvormidele erinevaid sõltuvusi.

Näide:

from setuptools import setup, Extension
import platform

if platform.system() == 'Windows':
 extra_compile_args = ['/O2', '/EHsc']
else:
 extra_compile_args = ['-O3']

setup(
 name='my_package',
 version='0.1.0',
 ext_modules=[
 Extension(
 'my_package.my_extension',
 ['my_package/my_extension.c'],
 extra_compile_args=extra_compile_args,
 ),
 ],
)

4. Platvormispetsiifiliste Wheelide ehitamine

Platvormispetsiifiliste Wheelide ehitamiseks peate kasutama iga sihtplatvormi jaoks sobivat ehituskeskkonda. See võib hõlmata virtuaalmasinate või konteinertehnoloogiate nagu Docker kasutamist.

Näide: Windows 64-bitise Wheeli ehitamiseks peate käivitama ehitusprotsessi Windows 64-bitisel süsteemil, millele on paigaldatud Microsoft Visual C++ kompilaator.

Parimad tavad Wheeli paketi loomisel

Parimate tavade järgimine tagab, et teie Wheeli paketid on usaldusväärsed, hooldatavad ja hõlpsasti kasutatavad. Siin on mõned peamised soovitused:

1. Kasutage semantilist versioonimist (SemVer)

Järgige semantilist versioonimist (SemVer) järjepidevaks versioonimiseks. SemVer kasutab kolmeosalisest versiooninumbrit (MAJOR.MINOR.PATCH), et näidata igas väljalaskes tehtud muudatuste tüüpi.

• MAJOR: Näitab kokkusobimatuid API muudatusi.
• MINOR: Näitab uusi funktsioone, mis on tagasiühilduvad.
• PATCH: Näitab veaparandusi, mis on tagasiühilduvad.

Näide: Funktsiooni parameetrite muutmine viisil, mis rikub olemasolevat koodi, tooks kaasa suurema versioonihüppe (nt 1.0.0-lt 2.0.0-le). Uue funktsiooni lisamine olemasolevaid muutmata tooks kaasa väiksema versioonihüppe (nt 1.0.0-lt 1.1.0-le). Vea parandamine tooks kaasa paigutusversioonihüppe (nt 1.0.0-lt 1.0.1-le).

2. Kaasake README.md fail

Kaasake README.md fail, mis annab paketi kohta üksikasjaliku kirjelduse, sealhulgas paigaldusjuhised, kasutusnäited ja panustamisjuhised. See aitab kasutajatel teie paketi kasutamist mõista ja julgustab panustama.

3. Kirjutage selge ja lühike dokumentatsioon

Kirjutage oma paketi kohta selge ja lühike dokumentatsioon, sealhulgas API dokumentatsioon, õpetused ja näited. Kasutage tööriistu nagu Sphinx või Read the Docs, et genereerida dokumentatsioon oma koodikommentaaridest.

4. Kasutage litsentsi

Valige oma paketile litsents, mis määratleb selgelt tingimused, mille alusel seda saab kasutada, muuta ja levitada. Levinumad litsentsid on MIT, Apache 2.0 ja GPL.

5. Testige oma paketti põhjalikult

Testige oma paketti põhjalikult, kasutades automatiseeritud testimistööriistu nagu pytest või unittest. Kirjutage ühiktestid, integratsioonitestid ja otsast-lõpuni testid, et tagada teie paketi korrektne toimimine erinevates stsenaariumides.

6. Kasutage pidevat integratsiooni (CI)

Kasutage pideva integratsiooni (CI) tööriistu nagu GitHub Actions, GitLab CI või Jenkins, et oma paketti automaatselt ehitada ja testida iga kord, kui koodibaasis muudatusi tehakse. See aitab vigu varakult tabada ja tagab, et teie pakett on alati töökorras.

7. Allkirjastage oma paketid

Allkirjastage oma paketid, et kontrollida nende autentsust ja terviklikkust. See aitab vältida pahatahtlike osapoolte rikutud pakettide levitamist. Kasutage oma pakettide allkirjastamiseks tööriistu nagu gpg või keyring.

Edasijõudnud Wheeli tehnikad

Keerukamate kasutusjuhtude puhul kaaluge neid tehnikaid:

1. build-i kasutamine

Pakett build pakub moodsat ja standardiseeritud viisi Pythoni pakettide ehitamiseks. See toetab nii Wheeli kui ka lähtekoodijaotusi ja pakub lihtsamat liidest kui setuptools.

pip install build
python -m build

2. Muudetavad paigaldused (Editable Installs)

Muudetavad paigaldused võimaldavad teil paketi paigaldada viisil, mis seob otse lähtekoodiga. See on kasulik arendamiseks, kuna lähtekoodi muudatused kajastuvad koheselt paigaldatud paketis ilma seda uuesti paigaldamata.

pip install -e .

3. Ehitusprotsessi kohandamine

Ehitusprotsessi saate kohandada, määratledes kohandatud ehitusskripte või kasutades ehitussüsteeme nagu Meson või CMake. See võimaldab teil käsitleda keerukamaid ehitusstsenaariume, näiteks C-laiendite ehitamist spetsiifiliste kompilaatorilippudega või linkimist väliste teekide vastu.

4. auditwheel-i kasutamine

Tööriista auditwheel kasutatakse Linuxi Wheelide auditeerimiseks ja parandamiseks, mis sisaldavad jagatud teeke. See tagab, et Wheel sisaldab kõiki vajalikke sõltuvusi, et töötada paljudes Linuxi jaotustes.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

Järeldus

Wheeli jaotusformaat on oluline tööriist Pythoni arendajatele, kes püüdlevad tõhusa, usaldusväärse ja turvalise pakettide levitamise poole. Järgides käesolevas juhendis kirjeldatud samme ja võttes kasutusele parimad tavad, saate luua Wheeli pakette, mis lihtsustavad paigaldusprotsessi, vähendavad sõltuvusi ehitustööriistadest ja parandavad üldist kasutajakogemust. Olenemata sellest, kas levitate pakette avatud lähtekoodiga kogukonnale või juurutate sisemisi rakendusi, on Wheeli formaadi mõistmine ja kasutamine väärtuslik oskus igale Pythoni arendajale. Kuna Python areneb edasi, tagab moodsate pakendamispraktikate, nagu Wheel, omaksvõtmine, et teie projektid jäävad ülemaailmsele publikule ligipääsetavaks ja hooldatavaks.

Neid tavasid omaks võttes aitate kaasa tugevamale ja ligipääsetavamale Pythoni ökosüsteemile kogu maailmas.